home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 43 / Amiga Format CD43 (1999)(Future Publishing)(GB)(Track 1 of 2)[!][issue 1999-09].iso / -in_the_mag- / banging_the_metal / peek+poke / peek+poke.text < prev    next >
Text File  |  1999-04-03  |  10KB  |  223 lines
  1. Structured PEEKs and POKEs for the Amiga Shell!
  2. ===============================================
  3.  
  4.  
  5. INTRODUCTION
  6.  
  7. Would you like to be able to read analogue joysticks, switch the audio filter,
  8. check library and device versions, reset MIDI devices, blink the power LED,
  9. check your Amiga chip set or CPU type, start and stop floppy drive motors or
  10. change the sex of the narrator device - all from the comfort of your shell or
  11. a Script file?
  12.  
  13. All these and much more - including numerous ways to crash the machine - are
  14. now available via structured PEEK and POKE extensions for the Amiga Shell.
  15.  
  16. These new, small, commands are either a great leap backwards or a small lunge
  17. forwards for the Amiga. They are freely distributable with stand-alone source
  18. in assembler, and run on any machine with at least Workbench 2.0.
  19.  
  20.  
  21. OVERVIEW
  22.  
  23. Like old-fashioned BASIC PEEKs and POKEs, you can read or (if you must) write
  24. the bytes at any memory address. Unlike most BASICs, you can also read and
  25. write words (16 or 32 bits wide) and read null-terminated strings from RAM. 
  26. The 'structured' extensions mean that addresses can be specified relative to
  27. the base of hardware or software resources, identified by name - so addresses
  28. can be relative to the start of CUSTOM chip or CIA registers, or any library,
  29. device or resource you choose to name.
  30.  
  31. Numeric values can be read and written in decimal, hexadecimal or binary bases.
  32. Decimal parameters may be signed or unsigned values. Indirect addressing is
  33. available, and comes in handy when looking through pointers in a structure.
  34.  
  35. These commands were written for three purposes:
  36.  
  37.   (1) To allow low-level access to hardware and memory, from the CLI.
  38.   (2) To prevent the need to write little bits of code for each POKE.
  39.   (3) To experiment with some non-trivial ReadArgs parameter parsing.
  40.   (0) To annoy people who believe that POKEs are a thing of the past.
  41.  
  42.  
  43. SIMPLE EXAMPLES
  44.  
  45. These examples show the flexible format of various acceptable parameters:
  46.  
  47.  POKE ciaa 0 2        - Turns the audio filter off
  48.  POKE CIAA 0 0        - Turns the audio filter on
  49.  PEEK L 4            - Returns the EXEC library base address
  50.  PEEK CUSTOM 18        - Controller 0 left paddle position
  51.  PEEK CUSTOM 19                  - Controller 0 right paddle position
  52.  PEEK Res potgo WORD 20    - Version number of POTGO.RESOURCE
  53.  peek word lib dos 22        - Revision number of DOS.LIBRARY
  54.  peek lib exec long 42    - Contents of EXEC cold-capture vector
  55.  POKE CUSTOM WORD 48 511    - Sends MIDI RESET to the serial port
  56.  POKE WORD dev="narrator" 48 90  - Sets speech rate to 90 words/minute
  57.  peek LONG lib "graphics" 50    - Address of current Copper List
  58.  POKE W DEV "narrator" 54 1      - Narrator attempts a female voice
  59.  peek lib="exec" 62 long    - Returns the top of Chip Memory
  60.  peek 62 word lib graphics    - Returns the current screen display mode
  61.  poke w Dev narrator 62 16    - Set -12 dB Narrator speech volume
  62.  PEEK W lib "graphics" 232    - Microseconds per scan line * 256
  63.  peek lib graphics.library 236    - ChipSet revision, e.g. OCS/ECS/AGA  
  64.  POKE CIAB 256 119        - Start motor of DF0, stop other drives
  65.  poke 256 129 ciab        - Stop all floppy disk drive motors
  66.  PEEK long library "exec" 276    - Returns base address of this task 
  67.  peek LIBRARY="exec" w 296    - Returns ATTN_FLAGS (CPU type)
  68.  POKE LIB "exec.library" 297 1    - Pretend this CPU is a 68010!
  69.  Peek LIB "exec" 530        - Returns the vertical blanking frequency
  70.  PEEK 531 lib exec        - Returns power supply frequency in Hertz
  71.  PEEK LONG Library "exec" 568    - Number of timer 'E clocks' per second
  72.  PEEK CIAB 2048        - Low byte of 24 bit scan-line counter
  73.  PEEK dev=parallel string long 10 - "parallel.device", or "pit.device" if
  74.                 MapDevice parallel 0 to pit 0 is active.
  75.  
  76. See Mapping The Amiga, The Amiga Guru Book and the Include files for lots
  77. more interesting and dangerous offsets. The 'best' and most hazardous ones
  78. are secret. If you're not sure, PEEK first and POKE afterwards (perhaps)!
  79. If you find any interesting or useful examples, please tell us about them.
  80.  
  81. WARNING
  82.  
  83. Library, device and resource offsets can vary between software releases,
  84. but all these have worked on all Amigas tested so far - with the exception
  85. of the narrator device POKEs which are version dependent. If in doubt,
  86. check the documentation (include files) for the devices (etc.) you are
  87. using, and use some precautionary PEEKs to determine the version you've
  88. got before you POKE into it.
  89.  
  90.  
  91. DETAILED ARGUMENTS
  92.  
  93. PEEK and POKE support (and may engender) lots of arguments, but almost all
  94. are optional. The simplest case is PEEK 4, which returns the byte from RAM
  95. address 4. PEEK LONG 4 returns the 32 bit contents of the address ExecBase.
  96. POKE 4 255 crashes the system by changing the first byte of that pointer!
  97.  
  98. First, a summary for those who grok Regular Expression templates:
  99.  
  100. PEEK    W=WORD/S,L=LONG/S,LIB=LIBRARY/K,DEV=DEVICE/K,RES=RESOURCE/K,
  101.            C=CUSTOM/S,CIAA/S,CIAB/S,AT/S,ADDRESS/A,VALUE/A
  102.  
  103. POKE    W=WORD/S,L=LONG/S,LIB=LIBRARY/K,DEV=DEVICE/K,RES=RESOURCE/K,AT/S
  104.            C=CUSTOM/S,CIAA/S,CIAB/S,H=HEX/S,BIN=BINARY/S,STRING/S,ADDRESS/A
  105.  
  106. Human beings may find it easier to understand the options by examining the
  107. examples, above, or by experimentation - the way most PEEKs and POKEs are
  108. traditionally worked out. What follows is a discussion of some less-obvious 
  109. details of the way arguments are handled.
  110.  
  111. The Device option always selects unit zero, with 0 in the 'flags' field.
  112.  
  113. Numeric values may be specified in decimal, binary with a % prefix, or
  114. hexadecimal if prefixed with $, 0X or 0x. Excessive values are reduced
  115. modulo the transfer size, e.g. POKE 0 $123 stores $23 and POKE WORD 0
  116. $123456 stores $3456. Thus conventional (decimal only) ReadArgs numeric
  117. parsing cannot be used for value and address arguments, so the /N does
  118. not appear in the argument template. Nonetheless, VALUE and ADDRESS
  119. arguments are numeric.
  120.  
  121. By default PEEK returns a decimal number, but it can be a string up to
  122. 32 bytes long (stopping after 32 bytes or at the first null) returned
  123. in quotes, if the STRING switch is supplied, a value in binary, or in
  124. hexadecimal, indicated by the HEX or H switch and $ prefix before the
  125. number for base 16. The BIN or BINARY switch sets base 2 and a % prefix. 
  126.  
  127. The AT parameter indicates indirect addressing. The long word at the
  128. specified address is read and used as a pointer to the required data.
  129. Absolutely no validity checks are performed.
  130.  
  131. The STRING parameter expects that the argument is the offset of a pointer
  132. to the required string rather than the offset of the start of the string.
  133.  
  134. Numeric parameters are 32 bit signed or unsigned decimal values. Results are
  135. unsigned bytes or words, signed long words. The default data size is BYTE -
  136. this is not a switch. Words and bytes are reduced modulo 65536 and modulo 256
  137. respectively. Device, Resource and library names are case- sensitive and the
  138. .suffix is assumed if not explicitly presented. All other keywords are
  139. case-insensitive. Quotes, verbose qualifiers and equals signs are optional.
  140. PEEK returns an ASCII string followed by a trailing space and a newline, or
  141. nothing if an error occurs.
  142.  
  143. You may specify the transfer size and device/resource/library/hardware base
  144. in any order, so PEEK WORD CUSTOM 18 means the same as PEEK 18 WORD CUSTOM or
  145. PEEK W 18 CUSTOM or PEEK CUSTOM WORD 18. The choice is yours. Unfortunately
  146. qualifiers (LIB, LIBRARY, RES, DEVICE etc) must appear just before the name
  147. of the library, resource or device which you want to use, * so you need to
  148. say PEEK LIB exec 530 as PEEK exec LIB 530 will not work. This limitation
  149. is imposed by Commodore's READARGS function.
  150.  
  151. POTENTIAL PITFALLS
  152.  
  153. There is deliberately no check for uneven-addressed words or long words.
  154. These cause an odd address guru on 68000/68010 systems, but work fine on
  155. later processors including all the current 32 bit Amiga models.
  156.  
  157. Attempts to access non-existent memory on a Zorro 3 Amiga cause a bus error
  158. after a delay of a fraction of a second, unless the relevant area is remapped
  159. by the MMU. Utilities such as WarpKick can do this, if required.
  160.  
  161. Combinations of switches are additive, so PEEK LIB exec CUSTOM 2 reads the
  162. byte at ExecBase + $DFF000 + 2, - which is unlikely to be very useful!
  163.  
  164.  
  165. SCRIPT EXAMPLES
  166.  
  167. PEEKs and POKEs can be useful in scripts, where they may be combined with
  168. conditional tests and arithmetic, using the other features of the Amiga
  169. shell. They can also be used from ARexx when the existing memory-access
  170. functions of ARexx are inadequate.
  171.  
  172. PEEK lib exec 297 returns a byte identifying the processor on the current
  173. computer. You can redirect this to an environment variable and use its value
  174. later in your shell script. For instance, this code checks the current CPU
  175. and writes an appropriate message if it's a 68040 and 68060:
  176.  
  177.   PEEK lib=exec 297 >env:CPU
  178.   IF $CPU equ 127
  179.     ECHO "68040 processor"
  180.   ELSE
  181.     IF $CPU equ 255
  182.       ECHO "68060 processor"
  183.     ENDIF
  184.   ENDIF
  185.  
  186. A similar script on the author's machine selects a '68040' or '68060' banner
  187. when the machine is started, depending on the processor installed that day.
  188.  
  189. EVAL can be very useful with PEEK environment variables. For instance this
  190. sequence finds the start address of any Commodore Kickstart ROM:
  191.  
  192.   PEEK LONG $FFFFEC >env:ROMsize
  193.   EVAL 65536*256-$ROMsize
  194.  
  195. The result from EVAL can be re-directed to an environment variable, as in the
  196. first line, if further processing is required.
  197.  
  198. FILES
  199.  
  200. One source file is used to implement both PEEK and POKE commands, depending
  201. on the setting of the symbol PEEK (1 for PEEK, 0 for POKE). Most of the
  202. comments in this document are also included in the assembler source, with
  203.  
  204.   Name    Bytes    Version    Date
  205.   
  206.   PEEK    1532    37.6    28 March 1997
  207.   POKE    1056    37.6    28 March 1997
  208.   PEEK.ASM 23917    37.6    28 March 1997
  209.   
  210. No include files are needed to re-assemble the code as all necessary constants
  211. are in the single source file.
  212.  
  213.  
  214. AUTHORS
  215.  
  216. PEEK and POKE was written by Simon N Goodwin (simon@studio.woden.com) with
  217. help from Tadek Knapik (tadek@student.uci.agh.edu.pl). YOUR suggestions for
  218. extra features or improvements are very welcome. In fact any response at all
  219. will be gratefully received. This is not cardware or shareware, but we'd
  220. still like to know if anyone (besides us) is using it. Please get in touch.
  221.  
  222.      AMIGA FOREVER - the last, best, hope for art computer enthusiasts!
  223.